Configuring Remote Web Services

The Remote Web Services table lets you configure up to seven Web-based (HTTP/S) services (Remote Web Services) provided by third-party, remote HTTP/S hosts (HTTP Remote Hosts). The following types of services can be offered by the remote hosts: Routing service, Call Status service, Topology Status service, QoS service, General service, and Registration Status service. For more information on these services, see the description of the 'Type' parameter below.

Remote Web Services are configured using two tables with "parent-child" relationship:

■ Remote Web Services table ("parent"): Defines the name of the Remote Web Service as well as other settings (e.g., type of service). This table is described below.
■ HTTP Remote Hosts table ("child"): Defines remote HTTP hosts (e.g., IP address) per Remote Web Service. For more information, see Configuring Remote HTTP Hosts.
● You can configure only one Remote Web Service for each of the following service types: Routing, Call Status, Topology Status, QoS, Registration Status, and Remote Monitoring.
● The Routing service also includes the Call Status and Topology Status services.
● The device supports HTTP redirect responses (3xx) only during connection establishment with the host. Upon receipt of a redirect response, the device attempts to open a new socket with the host and if this is successful, closes the current connection.

The following procedure describes how to configure Remote Web Services through the Web interface. You can also configure it through ini file [HTTPRemoteServices] or CLI (configure system > http-services > http-remote-services).

➢ To configure a remote Web service:
1. Open the Remote Web Services table (Setup menu > IP Network tab > Web Services folder > Remote Web Services).
2. Click New; the following dialog box appears:

3. Configure a remote Web service according to the parameters described in the table below.
4. Click Apply, and then save your settings to flash memory.

Remote Web Services Table Parameter Descriptions

Parameter

Description
General

'Index'
[Index]

Defines an index number for the new table row.

Note:

■ Each row must be configured with a unique index.
■ The parameter is mandatory.

'Name'

rest-name

[Name]

Defines a descriptive name, which is used when associating the row in other tables.

The valid value is a string of up to 40 characters.

Note:

■ Configure each row with a unique name.
■ The parameter is mandatory.
■ The parameter value cannot contain a forward slash (/).

'Type'

rest-message-type

[HTTPType]

Defines the type of service provided by the HTTP remote host:

■ [0] Routing = (Default) This option provides a call routing service, whereby the host (e.g., Routing server) determines the next hop of an incoming call on the path to its final destination. For more information on employing a third-party, routing server or ARM, see Centralized Third-Party Routing Server. This option also includes the services provided by the Call Status and Topology Status options.
■ [1] Call Status = This option provides a call status service for calls processed by the device. The device provides call status to the host by sending CDRs.
■ [2] Topology Status = This option provides a topology status service, which refers to all device configuration changes (add, edit and delete actions). The device sends topology status to the HTTP host, using the REST API command, TopologyStatus. For this service to be functional, you also need to enable the Topology Status service as described in Enabling Topology Status Services.

Topology status includes the following:

✔ IP Group Connectivity: Status is reported when the keep-alive mechanism, enabled for the associated Proxy Set, detects that the IP Group is unavailable, or when CAC thresholds (configured in the Admission Control table) associated with the IP Group are crossed.
✔ Trunk Group Availability: Status is reported when the trunk's physical state indicates that the trunk is unavailable. (Applicable only to the Gateway application.)
✔ Configuration Status: Status is reported when IP Groups, Trunk Groups, (Gateway application only) or SIP Interfaces that are configured to be used by remote Web-based services (i.e., the UsedByRoutingServer parameter is set to 1 - Used) are created or deleted. If you subsequently change the settings of the UsedByRoutingServer parameter or the 'Name' parameter, the device reports the change as a creation or deletion of the corresponding configuration entity.
■ [5] QoS = This option provides a call routing service based on Quality of Service (QoS). For more information, see Configuring QoS-Based Routing by Routing Server.
■ [8] General = This option can be used for the following services:
✔ Generating and sending CDRs to a REST server through REST API. The REST server is configured as an HTTP-based server (Remote Web Service). For more information, see Configuring CDR Reporting to REST Server.
✔ Querying (GET) HTTP servers using Call Setup Rules. The response from the server can be used for various functionality such as tag-based classification and routing. When configuring the Call Setup Rule, you need to configure the 'Request Target' parameter to the name of this Remote Web Service. For more information on Call Setup Rules, see Configuring Call Setup Rules.
✔ Requesting a Push Notification Server to wake a SIP user agent (typically, a mobile device) that is registered with the server for Push Notification Service, through REST API. The REST server (Push Notification Server) is configured as an HTTP-based server (Remote Web Service). For more information, see Configuring Push Notification Service.
■ [9] Registration Status = This option provides a call routing service based on registration status. The device periodically synchronizes its database of registered user agents (endpoints) with the third-party routing server or ARM (HTTP host) to keep it up to date, enabling the Routing server to use this information to perform correct and optimal routing decisions. For this service to be functional, you also need to enable the Registration Status service as described in Enabling Registration Status Services.
■ [10] Remote Monitoring = This option provides a remote monitoring of the device service when the device is located behind a NAT. The device sends its monitoring reports to this Remote Web Service (HTTP host). To enable remote monitoring and to select the report types that you want sent, see Remote Monitoring of Device behind NAT.

Note:

■ You can configure only one Remote Web Service for each of the following service types: Routing, Call Status, Topology Status, QoS, Registration Status, and Remote Monitoring.
■ The Routing option also includes the Call Status and Topology Status services.
■ If you don't configure the parameter to QoS, the device sends QoS reports to the Topology server.
■ For the Registration Status service, if you have not configured the parameter to Registration Status for any Remote Web Service, the device provides the service to the Remote Web Service for which you have configured the parameter to Topology Status.

'Path'

rest-path

[Path]

Defines the path (prefix) to the REST APIs.

The valid value is a string of up to 80 characters. The default is "api".

'Number of Connections'

http-num-connections

[NumOfSockets]

 

Defines the number of sockets that the device opens per HTTP remote host.

The valid value is 3. The default is 1.

Policy

'Policy in Group'

http-policy

[Policy]

Defines the mode of operation between hosts in a group, which are configured in the HTTP Remote Hosts table for the specific remote Web service.

■ [0] Round Robin = (Default) The device does load balancing of traffic across all the hosts in the group. Every consecutive message is sent to the next available host. The priority of the hosts determines the order in which the device sends the traffic.
■ [1] Sticky Primary = The device always attempts to send traffic to the host that has the highest priority in the group. If the host doesn't respond, the device sends the traffic to the next available host that has the highest priority. If the host that has the highest priority becomes available again, the device sends the traffic to this host.
■ [2] Sticky Next = The device initially attempts to send traffic to the host that has the highest priority in the group. If this host becomes unavailable (or is initially unavailable), the device sends the traffic to the next available host that has the highest priority and continues sending traffic to this host even if the highest-priority host later becomes available again.

Note: If you have configured multiple hosts with the same priority, their priority is determined by their order of appearance in the HTTP Remote Hosts table. For example, if two hosts are configured in rows Index 0 and Index 1 with priority 0, the host in Index 0 is considered higher priority.

'Policy between Groups'

http-policy-between-groups

[BetweenGroupsPolicy]

Defines the mode of operation between groups of hosts, which are configured in the HTTP Remote Hosts table for the specific remote Web service.

■ [1] Sticky Primary = (Default) The device always attempts to send traffic to the group that has the highest priority (e.g., Group 0). If none of the hosts in this group respond, the device attempts to send traffic to a host in a group that has the next highest priority (e.g., Group 1), and so on. Whenever a host in the group that has the highest priority (e.g., Group 0) becomes available again, the device sends the traffic to the host in this group.
■ [2] Sticky Next = The device initially attempts to send traffic to the group of hosts that has the highest priority (e.g., Group 0). If none of the hosts in the group respond, the device attempts to send traffic to a host in a group that has the next highest priority (e.g., Group 1). Even if the group of hosts that has the highest priority (e.g., Group 0) becomes available again, the device continues sending traffic to this lower priority group (e.g., Group 1) .

'Automatic Reconnect'

http-persistent-connection

[PersistentConnection]

Defines whether the HTTP connection with the host remains open or is only opened per request.

■ [0] Disable = The HTTP connection is created per client (user) request and remains connected until the server closes the connection.
■ [1] Enable = (Default) The device creates the HTTP connection once you have configured the service. If the server closes the connection, the device re-opens it. If the keep-alive timeout is configured, the device uses HTTP keep-alive messages to keep the connection open all the time.

Login Needed

http-login-needed

[LoginNeeded]

Enables the use of the AudioCodes proprietary REST API Login and Logout commands for connecting to the remote host. The commands verify specific information (e.g., software version) before allowing connectivity with the device.

■ [0] Disable = Commands are not used.
■ [1] Enable (default)

Note: The parameter is applicable only if you configure the 'Type' parameter to any value other than General.

Authentication

'Username'

rest-user-name

[AuthUserName]

Defines the username for HTTP authentication.

The valid value is a string of up to 80 characters. The default is "user".

'Password'

rest-password

[AuthPassword]

Defines the password for HTTP authentication.

The valid value is a string of up to 80 characters. The default is "password".

Note: The password cannot be configured with wide characters.

Security

'TLS Context'

rest-tls-context

[TLSContext]

Assigns a TLS Context (TLS configuration) for connection with the remote host.

By default, no value is defined.

To configure TLS Contexts, see Configuring TLS Certificates.

Note: The parameter is applicable only if the connection is HTTPS.

'Verify Certificate'

rest-verify-certificates

[VerifyCertificate]

Enables certificate verification when connection with the host is based on HTTPS.

■ [0] Disable = (Default) No certificate verification is done.
■ [1] Enable = The device verifies the authentication of the certificate received from the HTTPS peer. The device authenticates the certificate against the trusted root certificate store associated with the associated TLS Context (see 'TLS Context' parameter above) and if ok, allows communication with the HTTPS peer. If authentication fails, the device denies communication (i.e., handshake fails). The device can also authenticate the certificate by querying with an Online Certificate Status Protocol (OCSP) server whether the certificate has been revoked. This is also configured for the associated TLS Context.

Note: The parameter is applicable only if the connection is HTTPS.

'Verify Certificate Subject Name'

verify-cert-subject-name

[VerifyCertificateSubjectName]

Enables the verification of the TLS certificate subject name (Common Name / CN or Subject Alternative Name / SAN) when connection with the host is based on HTTPS.

■ [0] Off = (Default) No verification is done.
■ [1] On = The device verifies the subject name of the certificate received from the HTTPS peer. If the server's URL contains a hostname, it verifies the certificate against the hostname; otherwise, it verifies the certificate against the server's IP address. If authentication fails, the device denies communication (i.e., handshake fails).

Note: The parameter is applicable only if the connection is HTTPS.

Timeouts

'Response Timeout'

rest-timeout

[TimeOut]

Defines the TCP response timeout (in seconds) from the remote host. If one of the remote hosts doesn't respond to a request (e.g., HTTP GET method) within the specified timeout, the device closes the corresponding socket and attempts to connect to the next remote host.

The valid value is 1 to 65535. The default is 5.

Note: The global parameter for response timeout is described in Configuring a Routing Response Timeout.

'Keep-Alive Timeout'

rest-ka-timeout

[KeepAliveTimeOut]

Defines the duration/timeout (in seconds) in which HTTP-REST keep-alive messages are sent by the device if no other messages are sent. Keep-alive messages may be required for HTTP services that expire upon inactive sessions. For Remote Web Service whose 'Type' is Routing, Call Status, Topology Status, or QoS, proprietary keep-alive messages are sent. For 'Type' that is General, HTTP OPTIONS keep-alive messages are sent.

The valid value is 0 to 65535. The default is 0 (i.e., no keep-alive messages are sent).

Status

'Status'

(Read-only) Displays the status of the host associated with the Web service.

■ "Connected": At least one of the hosts is connected.
■ "Disconnected": All hosts are disconnected.

'Active Group'

(Read-only) Displays the currently active Group (by ID) that is associated with the Web service. This is the host group to where the device is currently sending traffic.

'Active Host'

(Read-only) Displays the currently active host (by name) that is associated with the Web service. This is the host (within the active group) to where the device is currently sending traffic.

Note: If traffic is sent to the hosts in a round-robin fashion (i.e., 'Policy in Group' parameter is configured to Round Robin), then this field displays "NA".